feat(pt_expt): auto-select O(N) NeighborGraph builder by default - #5903

This is the change the PR really makes, and it re-adds what #5912 removed.

On #5912 I raised this against an identical ladder:

This branch puts vesin on the default path, which contradicts the builder's own documented contract. [...] After this change, any environment with vesin.torch installed and without CUDA + nvalchemiops gets that per-frame Python loop by default. That includes runs under auto_batch_size, which deliberately batches many frames into a single _eval_model_graph call - exactly where the vectorised dense builder handles all frames at once and the vesin loop is worst. [...] Either prefer dense when nframes > 1, or update the contract to say vesin is now a default and re-examine whether the per-frame loop is acceptable there.

That rung was dropped and #5912 merged without it. This commit restores it and takes the second half of that either/or -- the module docstring is rewritten -- but not the first: there is no nframes gate, and no measurement re-examining the loop.

The reason I do not think the docstring rewrite settles it is that the repository already has an answer to this exact question, and it goes the other way. _select_neighbor_builder picks between the same two builders:

if device.type == "cpu" and nf == 1 and is_vesin_torch_available():
    return VesinNeighborList()

with the rationale stated directly above it: "Every other case -- any CUDA input or any multi-frame batch -- uses nvalchemiops, whose batched kernel amortizes the launch cost across frames." It takes nf, and it is called per forward. This resolver takes only device and is called once from _setup_neighbor_backend inside DeepEval.__init__, before any frame count exists -- so it cannot express that policy even if we wanted it to. That is a structural difference, not a parameter we forgot to thread through.

Three things make the exposure wider than it looks. vesin[torch] is an unconditional dependency of the torch extra, so this is the CPU default for essentially every pt user rather than an opt-in for people who installed something extra. auto_batch_size defaults to True, and _eval_model_graph receives whole batches from execute_all, so multi-frame is the normal case for dp test and dp model-devi, not the exception. And the builder's own scope note puts the cost at "~1 ms/frame call overhead". For a small system over many frames the arithmetic points at a slowdown, which inverts the PR's stated goal.

What would resolve it, in order of preference: move the resolution to call time and gate on nf == 1 for vesin, matching _select_neighbor_builder; or keep construction-time resolution and drop the vesin rung, leaving it explicit opt-in as #5912 concluded; or keep it and post a benchmark over a realistic dp test batch showing dense is not faster. Any of the three is fine by me -- what I do not want is the decision being reversed silently.

The summary describes two changes that are not in this diff.

It says the PR will "Flip the pt_expt model-level default (None / "auto") from hard-coded "dense" to that ladder" and "use the same helper in ... compiled training's eager _forward_graph". Neither deepmd/pt_expt/model/make_model.py nor deepmd/pt_expt/train/training.py appears in the changed files, and both still resolve the same way they did before:

• make_model.py _resolve_graph_method still ends at getattr(self, "neighbor_graph_method", "dense"), so a model driven directly still defaults to dense on every device;
• training.py still imports only resolve_neighbor_graph_method, and _forward_graph still reads getattr(_model, "neighbor_graph_method", "dense").

build_neighbor_graph_for_method also has no "auto" branch -- it raises ValueError on anything it does not recognise -- so "auto" could not reach it even if the model default did produce it.

I think this is stale text rather than a missing change: those two flips landed in #5912 and #5913, which are already ancestors of this branch. The "Why existing tests missed this" paragraph has the same problem, since it describes fixing compiled training's hardcoded dense. Worth rewriting the body to what the commit does -- add vesin to the inference auto ladder and extract the shared helper -- because as written a reviewer would look for a model-level behaviour change that is not here, and a bisect later would be misled about where the flip came from.

Missing the numpydoc sections the rest of this module uses.

This is a public function -- no leading underscore, imported by deep_eval.py -- and its sibling resolve_neighbor_graph_method a few lines below carries full Parameters / Returns / Raises blocks. This one documents the ladder in prose and a bullet list with no Parameters for device and no Returns for the str.

_select_neighbor_builder in deepmd/pt/model/model/sezm_model.py, which does the analogous job, also documents nf and device under Parameters and its return under Returns. Matching that is a small edit and keeps the API docs uniform.

These five cases pin the ladder, and I want to say they are the right shape -- patching availability and device rather than recomputing the cascade in the assertion is exactly what was missing from the equivalent test on #5912.

The gap is that they are the only new coverage, and they are pure resolver assertions: they never build a graph. The cross-builder numerical checks that do build one, test_vesin_matches_dense_energy_force and test_nv_matches_dense_energy_force further up this file, share the _eval helper, and it is single-frame:

coord = torch.tensor(rng.random((1, 6, 3)) * 4.0, ...)

So parity between vesin and dense is established only at nf == 1 -- the regime the vesin builder's own docstring says it is "intended for" -- while this PR makes vesin the default precisely for the batched regime, where nothing compares it against dense. That matters slightly more than a generic coverage note because the graph lower accumulates with segment_sum over edges and edge ordering after canonicalize is an independent implementation per builder, so multi-frame agreement does not follow from single-frame agreement; it needs its own case.

A parametrization of _eval over nf in {1, 4} would cover it, and it is the test I would want in place before the default moves, whichever way the vesin question above is settled.